home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / programming / c / requestlib / doku / reqtools.doc next >
Text File  |  1999-06-14  |  70KB  |  2,031 lines
  1. TABLE OF CONTENTS
  2.  
  3. reqtools.library/rtAllocRequestA
  4. reqtools.library/rtChangeReqAttrA
  5. reqtools.library/rtCloseWindowSafely
  6. reqtools.library/rtEZRequestA
  7. reqtools.library/rtFileRequestA
  8. reqtools.library/rtFontRequestA
  9. reqtools.library/rtFreeFileList
  10. reqtools.library/rtFreeReqBuffer
  11. reqtools.library/rtFreeRequest
  12. reqtools.library/rtGetLongA
  13. reqtools.library/rtGetStringA
  14. reqtools.library/rtGetVScreenSize
  15. reqtools.library/rtLockWindow
  16. reqtools.library/rtPaletteRequestA
  17. reqtools.library/rtReqHandlerA
  18. reqtools.library/rtScreenModeRequestA
  19. reqtools.library/rtScreenToFrontSafely
  20. reqtools.library/rtSetReqPosition
  21. reqtools.library/rtSetWaitPointer
  22. reqtools.library/rtSpread
  23. reqtools.library/rtUnlockWindow
  24.  
  25. reqtools.library/rtAllocRequestA             reqtools.library/rtAllocRequestA
  26.  
  27.     NAME
  28.     rtAllocRequestA -- Allocate ReqTools requester structure.
  29.  
  30.     SYNOPSIS
  31.     req = rtAllocRequestA( type, taglist );
  32.  
  33.     APTR rtAllocRequestA( ULONG, struct TagItem * );
  34.     D0                    D0     A0
  35.  
  36.     req = rtAllocRequest( type, tag1, ... );
  37.  
  38.     APTR rtAllocRequest( ULONG, Tag, ... );
  39.  
  40.     DESCRIPTION
  41.     Allocates a requester structure for you in a future compatible
  42.     manner. This is the only way to properly allocate a rtFileRequester,
  43.     rtFontRequester, rtReqInfo or rtScreenModeRequester structure. The
  44.     structure will be initialized for you.
  45.  
  46.     Use rtFreeRequest() to free the requester structure when you no
  47.     longer need it.
  48.  
  49.     INPUTS
  50.     type    - type of structure to allocate, currently RT_REQINFO,
  51.         RT_FILEREQ, RT_FONTREQ or RT_SCREENMODEREQ.
  52.     taglist - pointer to array of tags (currently always NULL).
  53.  
  54.     TAGS
  55.     no tags defined yet
  56.  
  57.     RESULT
  58.     req - pointer to the requester allocated or NULL if no memory.
  59.  
  60.     BUGS
  61.     none known
  62.  
  63.     SEE ALSO
  64.     rtFreeRequest()
  65.  
  66. reqtools.library/rtChangeReqAttrA           reqtools.library/rtChangeReqAttrA
  67.  
  68.     NAME
  69.     rtChangeReqAttrA -- Change ReqTools requester attributes.
  70.  
  71.     SYNOPSIS
  72.     [long =] rtChangeReqAttrA( req, taglist );
  73.  
  74.     [LONG] rtChangeReqAttrA( APTR, struct TagItem * );
  75.     [D0]                     A1    A0
  76.  
  77.     [long =] rtChangeReqAttr( req, tag1, ... );
  78.  
  79.     [LONG] rtChangeReqAttr( APTR, Tag, ... );
  80.  
  81.     DESCRIPTION
  82.     Change requester attributes with supplied taglist. This is the only
  83.     correct way to change the attributes listed below.
  84.  
  85.     The return code from rtChangeReqAttrA() should be ignored unless
  86.     stated otherwise.
  87.  
  88.     Don't pass the tags listed below to the requester itself (unless
  89.     documented otherwise). They will not be recognized.
  90.  
  91.     INPUTS
  92.     req     - pointer to requester.
  93.     taglist - pointer to array of tags.
  94.  
  95.     TAGS
  96.     For the file requester:
  97.  
  98.     RTFI_Dir - (char *)
  99.         Name of new directory to position file requester in. The
  100.         requester's buffer will be deallocated.
  101.  
  102.     RTFI_MatchPat - (char *) New pattern string to match files on.
  103.  
  104.     RTFI_AddEntry - (BPTR) THIS *MUST* BE THE LAST TAG (just before
  105.         TAG_END)! Tagdata must hold a lock on a file or directory you
  106.         want to add to the file requester's buffer. The lock should
  107.         have been obtained using Lock(), and you must unlock this lock
  108.         yourself. It is your responsibility to make sure the file or
  109.         directory is indeed in the directory the file requester is in.
  110.         If the entry is already in the file requester's buffer it will
  111.         simply be updated.
  112.         It is harmless to use this tag if the requester's buffer is not
  113.         initialized. rtChangeReqAttr() will return a boolean to
  114.         indicate success or failure (out of memory).
  115.  
  116.     RTFI_RemoveEntry - (char *) Name of file or directory you want to
  117.         remove from the file requester's buffer. It is your
  118.         responsibility to make sure the file or directory is indeed in
  119.         the directory the file requester is in.
  120.         It is harmless use this tag if the requester's buffer is not
  121.         initialized.
  122.  
  123.     For the font requester:
  124.  
  125.     RTFO_FontName - (char *) Set the name of the currently selected
  126.         font.
  127.  
  128.     RTFO_FontHeight - (UWORD) Set the fontsize of the currently
  129.         selected font.
  130.  
  131.     RTFO_FontStyle - (UBYTE) Set the style of the current font.
  132.  
  133.     RTFO_FontFlags - (UBYTE) Set the flags of the current font.
  134.  
  135.     For the screenmode requester [V38]:
  136.  
  137.     RTSC_ModeFromScreen - (struct Screen *) Screen to get mode
  138.         attributes from.
  139.  
  140.         NOTE: You must make sure the mode this screen is in will be
  141.             accepted by the screen mode requester. Otherwise it will
  142.             automatically cancel. For example, you use
  143.             RTDI_ModeFromScreen on a HAM screen and you haven't set the
  144.             SCREQF_NONSTDMODES flag.
  145.             Note that you must use this tag _before_ the four tags
  146.             below because this tag will set the width, height, depth
  147.             and autoscroll.
  148.  
  149.     RTSC_DisplayID - (ULONG) Set 32-bit mode id of selected mode. The
  150.         width and height will be set to the default (visible) width and
  151.         height, and the depth will be set to maximum. Also read note
  152.         above. Note that you must use this tag _before_ the three tags
  153.         below because this tag will set the width, height and depth to
  154.         default values.
  155.  
  156.     RTSC_DisplayWidth - (UWORD) Set width of display. Must come after
  157.         RTSC_DisplayID or RTSC_ModeFromScreen tags.
  158.  
  159.     RTSC_DisplayHeight - (UWORD) Set height of display. Must come after
  160.         RTSC_DisplayID or RTSC_ModeFromScreen tags.
  161.  
  162.     RTSC_DisplayDepth - (UWORD) Set depth of display. Must come after
  163.         RTSC_DisplayID or RTSC_ModeFromScreen tags.
  164.  
  165.     RTSC_AutoScroll - (BOOL) Boolean state of autoscroll checkbox. Must
  166.         come after RTSC_ModeFromScreen tag.
  167.  
  168.     RTSC_OverscanType - (ULONG) Set type of overscan. Set to 0 for
  169.         regular size, otherwise use OSCAN_... constants. See
  170.         'intuition/screens.[h|i]'.
  171.  
  172.     RESULT
  173.     none (except when RTFI_AddEntry tag is used, see above)
  174.  
  175.     BUGS
  176.     none known
  177.  
  178.     SEE ALSO
  179.     dos.library/Lock()
  180.  
  181. reqtools.library/rtCloseWindowSafely     reqtools.library/rtCloseWindowSafely
  182.  
  183.     NAME
  184.     rtCloseWindowSafely [V38] -- Close shared IDCMP window.
  185.  
  186.     SYNOPSIS
  187.     rtCloseWindowSafely( window );
  188.  
  189.     void rtCloseWindowSafely( struct Window * );
  190.                               A0
  191.  
  192.     DESCRIPTION
  193.     Closes a window which shares its IDCMP port with another window.
  194.     All the pending messages (concerning this window) on the port will
  195.     be removed and the window will be closed.
  196.  
  197.     Do not use this function to close windows which have an IDCMP port
  198.     set up by Intuition. If you do the port will be left in memory!
  199.  
  200.     If you intend to open a lot of windows all sharing the same IDCMP
  201.     port it is easiest if you create a port yourself and open all
  202.     windows with newwin.IDCMPFlags set to 0 (this tells Intuition to
  203.     NOT set up an IDCMP port). After opening the window set the
  204.     win->UserPort to your message port and call ModifyIDCMP() to set
  205.     your IDCMP flags.
  206.  
  207.     When you then receive messages from intuition check the
  208.     imsg->IDCMPWindow field to find out what window they came from and
  209.     act upon them.
  210.  
  211.     When closing your windows call rtCloseWindowSafely() for all of
  212.     them and delete your message port. Easy peasy :-)
  213.  
  214.     NOTE: Only call rtCloseWindowSafely() for windows with a shared
  215.         IDCMP port. Do *NOT* call it for windows with an IDCMP port
  216.         created by Intuition!
  217.  
  218.     INPUTS
  219.     window - pointer to the window to be closed.
  220.  
  221.     RESULT
  222.     none
  223.  
  224.     NOTE
  225.     This function is for the advanced ReqTools user.
  226.  
  227.     BUGS
  228.     none known
  229.  
  230.     SEE ALSO
  231.     intuition.library/CloseWindow()
  232.  
  233. reqtools.library/rtEZRequestA                   reqtools.library/rtEZRequestA
  234.  
  235.     NAME
  236.     rtEZRequestA -- Open a query requester.
  237.  
  238.     SYNOPSIS
  239.     ret = rtEZRequestA( bodyfmt, gadfmt, reqinfo, argarray, taglist );
  240.  
  241.     ULONG rtEZRequestA
  242.         ( char *, char *, struct rtReqInfo *, APTR, struct TagItem * );
  243.     D0    A1      A2      A3                  A4    A0
  244.  
  245.     ret = rtEZRequest
  246.         ( bodyfmt, gadfmt, reqinfo, taglist, arg1, arg2, ... );
  247.  
  248.     ULONG rtEZRequest
  249.         ( char *, char *, struct rtReqInfo *, struct TagItem *, ... );
  250.  
  251.     ret = rtEZRequestTags
  252.         ( bodyfmt, gadfmt, reqinfo, argarray, tag1, ... );
  253.  
  254.     ULONG rtEZRequestTags
  255.         ( char *, char *, struct rtReqInfo *, APTR, Tag, ... );
  256.  
  257.     DESCRIPTION
  258.     This function puts up a requester for you and waits for a response
  259.     from the user. If the response is positive, this procedure returns
  260.     TRUE. If the response is negative, this procedure returns FALSE.
  261.     The function may also return an IDCMP flag or a value corresponding
  262.     with one of other possible responses (see below).
  263.  
  264.     'gadfmt' may contain several possible responses. Separate these
  265.     responses by a '|'. For example: "Yes|No", or 'Yes|Maybe|No". The
  266.     responses should be typed in the same order as they will appear on
  267.     screen, from left to right. There is no limit to the number of
  268.     responses other than the width of the screen the requester will
  269.     appear on.
  270.  
  271.     'bodyfmt' can contain newlines ('\n', ASCII 10). This will cause a
  272.     new line to be started (surprise, surprise :-).
  273.     You may also include printf() style formatting codes. The format
  274.     arguments should be pointed to by 'argarray'.
  275.     You can use formatting codes in 'gadfmt' as well. The arguments for
  276.     this format string should follow the ones for 'bodyfmt'.
  277.  
  278.     NOTE: The formatting is done by exec.library/RawDoFmt(), so be
  279.         aware that to display a 32-bit integer argument you must use
  280.         "%ld", not "%d", since RawDoFmt() is "word-oriented."
  281.  
  282.     The second and third function use a variable number of arguments.
  283.     These functions can be found in 'reqtools[nb].lib'.
  284.     The second function has the RawDoFmt() arguments as variable args,
  285.     the third the tags. If you need both this is what you can do:
  286.  
  287.     ...
  288.     {
  289.        ULONG tags[] = { RTEZ_ReqTitle, (ULONG)"mytitle", TAG_END };
  290.  
  291.        rtEZRequest ("String, num: %s, %ld", "Ok", NULL,
  292.                                        (struct TagItem *)tags, "six", 6);
  293.     }
  294.     ...
  295.  
  296.     You can satisfy the requester with the following keyboard shortcuts:
  297.         'Y' or Left Amiga 'V' for a positive response,
  298.         ESC, 'N', 'R' or Left Amiga 'B' for a negative response.
  299.  
  300.     If EZREQF_NORETURNKEY is _not_ set (see RTEZ_Flags below) the
  301.     RETURN key is also accepted as a shortcut for the positive response
  302.     (can be changed using RTEZ_DefaultResponse, see below). The
  303.     response that will be selected when you press RETURN will be
  304.     printed in bold.
  305.  
  306.     The EZREQF_LAMIGAQUAL flag should be used when you put up a
  307.     requester for a destructive action (e.g. to delete something). When
  308.     it is set the keyboard shortcuts are limited to Left Amiga 'V' and
  309.     'B' so it is harder to accidently select something you will regret.
  310.     Note that the RETURN and ESC key remain active!  To disable the
  311.     RETURN key use the EZREQF_NORETURNKEY flag. The ESC key cannot be
  312.     disabled.
  313.  
  314.     You may pass a NULL for 'gadfmt', but make sure you know what you
  315.     are doing. Passing a NULL opens an EZRequester with NO responses,
  316.     just a body text. This implies the user has no means of "answering"
  317.     this requester. You must therefore use the RT_IDCMPFlags tag to
  318.     allow some other events to end the requester (e.g.
  319.     IDCMP_MOUSEBUTTONS, IDCMP_INACTIVEWINDOW,...) or you must make use
  320.     of the ReqHandler feature. Using a requester handler you can end
  321.     the requester by program control. This way you can e.g. put up a
  322.     requester before you start loading a file and remove it after the
  323.     file has been loaded. Do not pass an empty string as 'gadfmt'!
  324.  
  325.     'reqinfo' can be used to customize the requester. For greater
  326.     control use the tags listed below. The advantage of the rtReqInfo
  327.     structure is that it is global, where tags have to be specified
  328.     each function call. See libraries/reqtools.[hi] for a description
  329.     of the rtReqInfo structure.
  330.  
  331.     INPUTS
  332.     bodyfmt  - requester body text, can be format string a la RawDoFmt().
  333.     gadfmt   - text for gadgets (left to right, separated by '|') or NULL.
  334.     argarray - pointer to array of arguments for format string(s).
  335.     reqinfo  - pointer to a rtReqInfo structure allocated with
  336.         rtAllocRequest() or NULL.
  337.     taglist  - pointer to a TagItem array.
  338.  
  339.     TAGS
  340.     RT_Window - (struct Window *) Window that will be used to find the
  341.         screen to put the requester on. You *MUST* supply this if you
  342.         are a task calling this function and not a process! This is
  343.         because tasks don't have a pr_WindowPtr.
  344.  
  345.     RT_IDCMPFlags - (ULONG) Extra idcmp flags to return on. If one
  346.         these IDCMP flags causes the requester to abort the return code
  347.         will equal the flag in question.
  348.  
  349.     RT_ReqPos - (ULONG) One of the following:
  350.  
  351.         REQPOS_POINTER - requester appears where the mouse pointer is
  352.             (default).
  353.  
  354.         REQPOS_CENTERSCR - requester is centered on the screen.
  355.  
  356.         REQPOS_CENTERWIN - requester is centered in the window (only
  357.             works if the pr_WindowPtr of your process is valid or if you
  358.             use RT_Window). If RT_Window is NULL the requester will be
  359.             centered on the screen.
  360.  
  361.         REQPOS_TOPLEFTSCR - requester appears at the top left of the
  362.             screen.
  363.  
  364.         REQPOS_TOPLEFTWIN - requester appears at the top left of the
  365.             window (only works if the pr_WindowPtr of your process is
  366.             valid or if you use RT_Window).
  367.         
  368.         The requester will always remain in the visible part of the
  369.         screen, so if you use the Workbench 2.0 ScreenMode preferences
  370.         editor to enlarge your Workbench screen and you scroll around,
  371.         the requester will always appear in the part you can see.
  372.         REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR also apply to the
  373.         visible part of the screen. So if you use one of these the
  374.         requester will be appear in the center or the top left off what
  375.         you can see of the screen as opposed to the entire screen.
  376.         
  377.         REQPOS_CENTERWIN and REQPOS_TOPLEFTWIN fall back to
  378.         REQPOS_CENTERSCR or REQPOS_TOPLEFTSCR respectively when there
  379.         is no parent window. So you can safely use these without
  380.         worrying about the existence of a window.
  381.  
  382.     RT_LeftOffset - (ULONG) Offset of left edge of requester relative to
  383.         position specified with RT_ReqPos (does not offset the
  384.         requester when RT_ReqPos is REQPOS_POINTER).
  385.  
  386.     RT_TopOffset - (ULONG) Offset of top edge of requester relative to
  387.         position specified with RT_ReqPos (does not offset the
  388.         requester when RT_ReqPos is REQPOS_POINTER).
  389.  
  390.     RT_PubScrName - (char *) Name of public screen requester should
  391.         appear on. When this tag is used the RT_Window tag will be
  392.         ignored. If the public screen is not found the requester will
  393.         open on the default public screen.
  394.         
  395.         Only works on Kickstart 2.0! reqtools.library does not check
  396.         this, it is up to you *NOT* to use this tag on Kickstart 1.3 or
  397.         below! Note that the 1.3 version of reqtools.library also
  398.         understands and supports this tag (on 2.0).
  399.  
  400.     RT_Screen - (struct Screen *) Address of screen to put requester
  401.         on. You should never use this, use RT_Window or RT_PubScrName.
  402.  
  403.     RT_ReqHandler - (struct rtHandlerInfo **) Using this tag you can
  404.         start an "asynchronous" requester. ti_TagData of the tag must
  405.         hold the address of a pointer variable to a rtHandlerInfo
  406.         structure. The requester will initialize this pointer and will
  407.         return immediately after its normal initialization. The return
  408.         code will not be what you would normally expect. If the return
  409.         code is _not_ equal to CALL_HANDLER an error occurred and you
  410.         should take appropriate steps.
  411.         
  412.         If the return code was CALL_HANDLER everything went ok and the
  413.         requester will still be up! See the explanation for
  414.         rtReqHandlerA() below for the following steps you have to take.
  415.  
  416.     RT_WaitPointer - (BOOL) If this is TRUE the window calling the
  417.         requester will get a standard wait pointer set while the
  418.         requester is up. This will happen if you used the RT_Window tag
  419.         or if your process's pr_WindowPtr is valid. Note that after the
  420.         requester has finished your window will be ClearPointer()-ed.
  421.         
  422.         If you used a custom pointer in your window you will have to
  423.         re-set it, or not use the RT_WaitPointer tag and put up a wait
  424.         pointer yourself. If your program requires ReqTools V38 it is
  425.         advised you use RT_LockWindow instead. Defaults to FALSE.
  426.  
  427.     RT_LockWindow - (BOOL) [V38] If this is TRUE the window calling the
  428.         requester will get locked. It will no longer accept any user
  429.         input and it will get standard wait pointer set. This will
  430.         happen only if you used the RT_Window tag or if your process's
  431.         pr_WindowPtr is valid. RT_LockWindow will restore a custom
  432.         pointer if you have used one (unlike RT_WaitPointer). So you do
  433.         not have to worry about having to restore it yourself. It is
  434.         advised you use this tag as much as possible. Defaults to FALSE.
  435.  
  436.         Under Kickstart V39 the original window pointer will not be
  437.         restored if it was set using SetWindowPointer(). You will have
  438.         to restore the pointer yourself in this case.
  439.  
  440.     RT_ScreenToFront - (BOOL) [V38] Boolean indicating whether to pop
  441.         the screen the requester will appear on to the front. Default is
  442.         TRUE.
  443.  
  444.     RT_ShareIDCMP - (BOOL) [V38] Boolean indicating whether to share
  445.         the IDCMP port of the parent window. Use this tag together with
  446.         the RT_Window tag to indicate the window to share IDCMP with.
  447.         Sharing the IDCMP port produces less overhead, so it is advised
  448.         you use this tag. Defaults to FALSE.
  449.  
  450.     RT_Locale - (struct Locale *) [V38] Locale to determine what
  451.         language to use for the requester text. If this tag is not used
  452.         or its data is NULL, the system's current default locale will
  453.         be used. Default NULL.
  454.     RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call
  455.         this hook for each IDCMP message it gets that doesn't belong to
  456.         its window. Only applies if you used the RT_ShareIDCMP tag to
  457.         share the IDCMP port with the parent window. Parameters are as
  458.         follows:
  459.         
  460.             A0 - (struct Hook *) your hook
  461.             A2 - (struct rtReqInfo *) your requester info
  462.             A1 - (struct IntuiMessage *) the message
  463.         
  464.         After you have finished examining the message and your hook
  465.         returns, ReqTools will reply the message. So do not reply the
  466.         message yourself!
  467.  
  468.     RT_Underscore - (char) [V38] Indicates the symbol that precedes the
  469.         character in the gadget label to be underscored. This is to
  470.         define a keyboard shortcut for this gadget. Example: to define
  471.         the key 'Q' as a keyboard shortcut for "Quit" and 'N' for "Oh,
  472.         No!" you would use the tag RT_Underscore, '_' and pass as
  473.         gadfmt "_Quit|Oh, _No!". Do not use the symbol '%' as it is
  474.         used for string formatting. The usual character to use is '_'
  475.         like in the example.
  476.         
  477.         IMPORTANT: the shortcuts defined using RT_Underscore take
  478.             precedence of the default shortcuts! It is for example not
  479.             wise to use a 'N' for a positive response! Pick your
  480.             shortcuts carefully!
  481.  
  482.     RT_TextAttr - (struct TextAttr *) [V38] Use this font for the
  483.         requester. Default is to use the screen font. Note that the
  484.         font must already be opened by you. ReqTools will call
  485.         OpenFont() on this TextAttr, _not_ OpenDiskFont()!  If the font
  486.         cannot be opened using OpenFont() the default screen font will
  487.         be used.
  488.  
  489.     RTEZ_ReqTitle - (char *) Title of requester window, default is
  490.         "Request" unless the requester has less than 2 responses, then
  491.         the default title is "Information".
  492.  
  493.     RTEZ_Flags - (ULONG) Flags for rtEZRequestA():
  494.  
  495.         EZREQF_NORETURNKEY - turn off the RETURN key as shortcut for
  496.             positive response.
  497.  
  498.         EZREQF_LAMIGAQUAL - keyboard shortcuts are limited to Left
  499.             Amiga 'V' and 'B', ESC and RETURN.
  500.  
  501.         EZREQF_CENTERTEXT - centers each line of body text in the
  502.             requester window. Useful for about requesters.
  503.  
  504.     RTEZ_DefaultResponse - (ULONG) Response value that will be returned
  505.         when the user presses the return key. Will be ignored if the
  506.         EZREQF_NORETURNKEY flag is set. The text for this response will
  507.         be printed in bold. Default is 1.
  508.  
  509.     RESULT
  510.     ret - 1 (TRUE) for leftmost (positive) response, then each
  511.         consecutive response will return 1 more, the rightmost (false)
  512.         response will return 0 (FALSE), so 1,2,3,...,num-1,0 -- or
  513.         idcmp flag.
  514.  
  515.     NOTE
  516.     Automatically adjusts the requester to the screen font.
  517.  
  518.     rtEZRequestA() checks the pr_WindowPtr of your process to find the
  519.     screen to put the requester on.
  520.  
  521.     BUGS
  522.     none known
  523.  
  524.     SEE ALSO
  525.     exec.library/RawDoFmt(), rtReqHandlerA()
  526.  
  527. reqtools.library/rtFileRequestA               reqtools.library/rtFileRequestA
  528.  
  529.     NAME
  530.     rtFileRequestA -- Open a file requester.
  531.  
  532.     SYNOPSIS
  533.     ret = rtFileRequestA( filereq, filename, title, taglist );
  534.  
  535.     APTR rtFileRequestA
  536.         ( struct rtFileRequester *, char *, char *, struct TagItem * );
  537.     D0    A1                        A2      A3      A0
  538.  
  539.     ret = rtFileRequest( filereq, filename, title, tag1, ... );
  540.  
  541.     APTR rtFileRequest
  542.         ( struct rtFileRequester *, char *, char *, Tag, ... );
  543.  
  544.     DESCRIPTION
  545.     Get a directory and filename(s), or just a directory from the user.
  546.  
  547.     'filename' should point to an array of at least 108 chars. The
  548.     filename already in 'filename' will be displayed in the requester
  549.     when it comes up. When the requester returns 'filename' will
  550.     probably have changed.
  551.  
  552.     Using certain tags may result in the calling of a caller-supplied
  553.     hook.
  554.  
  555.     The hook will be called with A0 holding the address of your hook
  556.     structure (you may use the h_Data field to your own liking), A2 a
  557.     pointer to the requester structure calling the hook ('req') and A1
  558.     a pointer to an object. The object is variable and depends on what
  559.     your hook is for.
  560.  
  561.     This is an example of a hook suitable to be used with the
  562.     RTFI_FilterFunc tag:
  563.  
  564.     SAS/C users can define their function thus:
  565.  
  566.     BOOL __asm __saveds filterfunc(
  567.             register __a0 struct Hook *filterhook,
  568.             register __a2 struct rtFileRequester *req,
  569.             register __a1 struct FileInfoBlock *fib )
  570.     {
  571.         BOOL accepted = TRUE;
  572.  
  573.         /* examine fib to decide if you want this file in the requester */
  574.         ...
  575.         return( accepted );
  576.     }
  577.  
  578.     Your hook structure should then be initialized like this:
  579.  
  580.         filterhook->h_Entry = filterfunc;
  581.         /* in this case no need to initialize hook->h_SubEntry */
  582.         filterhook->h_Data = your_userdata_if_needed;
  583.  
  584.     You can also use a stub written in machine code to call your
  585.     function. (see 'utility/hooks.h')
  586.  
  587.     INPUTS
  588.     filereq  - pointer to a struct rtFileRequester allocated with
  589.         rtAllocRequestA().
  590.     filename - pointer to an array of chars (must be 108 bytes big).
  591.     title    - pointer to requester window title (null terminated).
  592.     taglist  - pointer to a TagItem array.
  593.  
  594.     TAGS
  595.     RT_Window - see rtEZRequestA()
  596.  
  597.     RT_ReqPos - see rtEZRequestA()
  598.  
  599.     RT_LeftOffset - see rtEZRequestA()
  600.  
  601.     RT_TopOffset - see rtEZRequestA()
  602.  
  603.     RT_PubScrName - see rtEZRequestA()
  604.  
  605.     RT_Screen - see rtEZRequestA()
  606.  
  607.     RT_ReqHandler - see rtEZRequestA()
  608.  
  609.     RT_WaitPointer - see rtEZRequestA()
  610.  
  611.     RT_LockWindow - [V38] see rtEZRequestA()
  612.  
  613.     RT_ScreenToFront - [V38] see rtEZRequestA()
  614.  
  615.     RT_ShareIDCMP - [V38] see rtEZRequestA()
  616.  
  617.     RT_Locale - [V38] see rtEZRequestA()
  618.  
  619.     RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call
  620.         this hook for each IDCMP message it gets that doesn't belong to
  621.         its window. Only applies if you used the RT_ShareIDCMP tag to
  622.         share the IDCMP port with the parent window. Parameters are as
  623.         follows:
  624.  
  625.             A0 - (struct Hook *) your hook
  626.             A2 - (struct rtFileRequester *) your requester
  627.             A1 - (struct IntuiMessage *) the message
  628.  
  629.         After you have finished examining the message and your hook
  630.         returns, ReqTools will reply the message. So do not reply the
  631.         message yourself!
  632.  
  633.     RT_Underscore - (char) [V38] Indicates the symbol that precedes the
  634.         character in a gadget's label to be underscored. This will also
  635.         define the keyboard shortcut for this gadget. Currently only
  636.         needed for RTFI_OkText. Usually set to '_'.
  637.  
  638.     RT_DefaultFont - (struct TextFont *) This tag allows you to specify
  639.         the font to be used in the requester when the screen font is
  640.         proportional. Default is GfxBase->DefaultFont. This tag is
  641.         obsolete in ReqTools 2.2 and higher.
  642.  
  643.     RT_TextAttr - (struct TextAttr *) [V38] Use this font for the
  644.         requester. Default is to use the screen font. Note that the
  645.         font must already be opened by you. ReqTools will call
  646.         OpenFont() on this TextAttr, _not_ OpenDiskFont()! If the font
  647.         cannot be opened using OpenFont() or if the font is
  648.         proportional the default screen font will be used (or the font
  649.         set with RT_DefaultFont).
  650.  
  651.     RTFI_Flags - (ULONG) Several flags:
  652.  
  653.         FREQF_NOBUFFER - do _not_ use a buffer to remember directory
  654.             contents for the next time the file requester is used.
  655.  
  656.         FREQF_MULTISELECT - allow multiple files to be selected.
  657.             rtFileRequest() will return a pointer to an rtFileList
  658.             structure which will contain all selected files. Use
  659.             rtFreeFileList() to free the memory used by this file list.
  660.  
  661.         FREQF_SELECTDIRS - set this flag if you wish to enable the
  662.             selecting of dirs as well as files. You *must* also set
  663.             FREQF_MULTISELECT. Directories will be returned together
  664.             with files in rtFileList, but with StrLen equal to -1. If
  665.             you need the length of the directory's name use strlen().
  666.  
  667.         FREQF_SAVE - Set this if you are using the requester to save or
  668.             delete something. Double-clicking will be disabled so it is
  669.             harder to make a mistake and select the wrong file. If the
  670.             user enters a non-existent directory in the drawer string
  671.             gadget, a requester will appear asking if the directory
  672.             should be created.
  673.  
  674.         FREQF_NOFILES - Set this if you want to use the requester to
  675.             allow the user to select a directory rather than a file.
  676.             Ideal for getting a destination dir. May be used with
  677.             FREQF_MULTISELECT and FREQF_SELECTDIRS.
  678.  
  679.         FREQF_PATGAD - When this is set a pattern gadget will be added
  680.             to the requester.
  681.  
  682.     RTFI_Height - (ULONG) Suggested height of file requester window.
  683.  
  684.     RTFI_OkText - (char *) Replacement text for "Ok" gadget, max 6
  685.         chars long.
  686.  
  687.     RTFI_VolumeRequest - (ULONG) [V38] The presence of this tag turns
  688.         the file requester into a volume/assign disk requester. This
  689.         requester can be used to get a device name ("DF0:", "DH1:",..)
  690.         or an assign ("C:", "FONTS:",...) from the user. The result of
  691.         this requester can be found in the filereq->Dir field. The
  692.         volume can also be changed with rtChangeReqAttrA() and the
  693.         RTFI_Dir tag. 
  694.  
  695.         Note that the user may edit the disk/assign, or enter a new
  696.         one. Note also that the real device name is returned, not the
  697.         name of the volume in the device. For example "DH1:", not
  698.         "Hard1:". The tag data (ULONG) is used to set following flags:
  699.  
  700.         VREQF_NOASSIGNS - Do not include the assigns in the list, only
  701.             the real devices.
  702.  
  703.         VREQF_NODISKS - Do not include devices, just show the assigns.
  704.  
  705.         VREQF_ALLDISKS - Show _all_ devices. Default behavior is to
  706.             show only those devices which have valid disks inserted
  707.             into them. So if you have no disk in drive DF0: it will not
  708.             show up. Set this flag if you do want these devices
  709.             included.
  710.  
  711.         NOTE: Do *NOT* use { RTFI_VolumeRequest, TRUE }! You are then
  712.             setting the VREQF_NOASSIGNS flag! Use { RTFI_VolumeRequest,
  713.             0 } for a normal volume requester.
  714.  
  715.         NOTE: If you use the RTFI_FilterFunc described below the third
  716.             parameter will be a pointer to a rtVolumeEntry structure
  717.             rather than a pointer to a FileInfoBlock structure! Tech
  718.             note: the DOS device list has been unlocked, so it is safe
  719.             to e.g. Lock() this device and call Info() on this lock.
  720.  
  721.         NOTE: A file requester structure allocated with
  722.             rtAllocRequest() should not be used for both a file and a
  723.             volume requester. Allocate two requester structures if you
  724.             need both a file and a volume requester in your program!
  725.  
  726.     RTFI_FilterFunc - (struct Hook *) [V38] Call this hook for each
  727.         file and directory in the directory being read (or for each
  728.         entry in the volume requester). Parameters are as follows:
  729.  
  730.         A0 - (struct Hook *) your hook
  731.         A2 - (struct rtFileRequester *) your filereq
  732.         A1 - (struct FileInfoBlock *) fib of file OR (struct
  733.             rtVolumeEntry *) device or assign in case of a volume
  734.             requester.
  735.  
  736.         If your hook returns TRUE the file will be accepted. If it
  737.         returns FALSE the file will be skipped and will not appear in
  738.         the requester.
  739.  
  740.         IMPORTANT NOTE: If you change your hook's behavior you _MUST_
  741.             purge the requester's buffer (using rtFreeReqBuffer())!
  742.  
  743.         IMPORTANT NOTE: When this callback hook is called from a volume
  744.             requester the pr_WindowPtr of your process will be set to
  745.             -1 so *no* DOS requesters will appear when an error occurs!
  746.  
  747.     RTFI_AllowEmpty - (BOOL) [V38] If RTFI_AllowEmpty is TRUE an empty
  748.         file string will also be accepted and returned. Defaults to
  749.         FALSE, meaning that if the user enters no filename the
  750.         requester will be canceled. You should use this tag as little
  751.         as possible!
  752.  
  753.     RESULT
  754.     ret - TRUE if the user selected a file (check 'filereq->Dir' for
  755.         the directory and 'filename' for the filename) or FALSE if the
  756.         requester was canceled -- or a pointer to a struct rtFileList
  757.         (if FREQF_MULTISELECT was used).
  758.  
  759.     NOTE
  760.     You CANNOT call the file requester from a task because it uses DOS
  761.     calls!
  762.  
  763.     Automatically adjusts the requester to the screen font.
  764.  
  765.     If the requester got too big for the screen because of a very large
  766.     font, the topaz.font will be used.
  767.  
  768.     rtFileRequest() checks the pr_WindowPtr of your process to find the
  769.     screen to put the requester on.
  770.  
  771.     BUGS
  772.     none known
  773.  
  774.     SEE ALSO
  775.  
  776. reqtools.library/rtFontRequestA               reqtools.library/rtFontRequestA
  777.  
  778.     NAME
  779.     rtFontRequestA -- Open a font requester.
  780.  
  781.     SYNOPSIS
  782.     bool = rtFontRequestA( fontreq, title, taglist );
  783.  
  784.     BOOL rtFontRequestA
  785.         ( struct rtFontRequester *, char *, struct TagItem * );
  786.     D0    A1                        A3      A0
  787.  
  788.     bool = rtFontRequest( fontreq, title, tag1, ... );
  789.  
  790.     BOOL rtFontRequest( struct rtFontRequester *, char *, Tag, ... );
  791.  
  792.     DESCRIPTION
  793.     Let the user select a font and a style (optional).
  794.  
  795.     INPUTS
  796.     fontreq  - pointer to a struct rtFontRequester allocated with
  797.         rtAllocRequestA().
  798.     title - pointer to requester window title (null terminated).
  799.     taglist - pointer to a TagItem array.
  800.  
  801.     TAGS
  802.     RT_Window - see rtEZRequestA()
  803.  
  804.     RT_ReqPos - see rtEZRequestA()
  805.  
  806.     RT_LeftOffset - see rtEZRequestA()
  807.  
  808.     RT_TopOffset - see rtEZRequestA()
  809.  
  810.     RT_PubScrName - see rtEZRequestA()
  811.  
  812.     RT_Screen - see rtEZRequestA()
  813.  
  814.     RT_ReqHandler - see rtEZRequestA()
  815.  
  816.     RT_WaitPointer - see rtEZRequestA()
  817.  
  818.     RT_LockWindow - [V38] see rtEZRequestA()
  819.  
  820.     RT_ScreenToFront - [V38] see rtEZRequestA()
  821.  
  822.     RT_ShareIDCMP - [V38] see rtEZRequestA()
  823.  
  824.     RT_Locale - [V38] see rtEZRequestA()
  825.  
  826.     RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call
  827.         this hook for each IDCMP message it gets that doesn't belong to
  828.         its window. Only applies if you used the RT_ShareIDCMP tag to
  829.         share the IDCMP port with the parent window. Parameters are as
  830.         follows:
  831.  
  832.         A0 - (struct Hook *) your hook
  833.         A2 - (struct rtFontRequester *) your requester
  834.         A1 - (struct IntuiMessage *) the message
  835.  
  836.         After you have finished examining the message and your hook
  837.         returns, ReqTools will reply the message. So do not reply the
  838.         message yourself!
  839.  
  840.     RT_Underscore - (char) [V38] Indicates the symbol that precedes the
  841.         character in a gadget's label to be underscored. This will also
  842.         define the keyboard shortcut for this gadget. Currently only
  843.         needed for RTFO_OkText. Usually set to '_'.
  844.  
  845.     RT_DefaultFont - (struct TextFont *) This tag allows you to specify
  846.         the font to be used in the requester when the screen font is
  847.         proportional. Default is GfxBase->DefaultFont. This tag is
  848.         obsolete in ReqTools 2.2 and higher.
  849.  
  850.     RT_TextAttr - [V38] see rtFileRequestA()
  851.  
  852.     RTFO_Flags - (ULONG) Several flags:
  853.  
  854.         FREQF_NOBUFFER - do not buffer the font list for subsequent
  855.             calls to rtFontRequestA().
  856.  
  857.         FREQF_FIXEDWIDTH - only show fixed-width fonts.
  858.  
  859.         FREQF_COLORFONTS - show color fonts also.
  860.  
  861.         FREQF_CHANGEPALETTE - change the screen's palette to match that
  862.             of a selected color font.
  863.  
  864.         FREQF_LEAVEPALETTE - leave the palette as it is when exiting
  865.             rtFontRequestA() Useful in combination with
  866.             FREQF_CHANGEPALETTE.
  867.  
  868.         FREQF_SCALE - allow fonts to be scaled when they don't exist in
  869.             the requested size. (works on Kickstart 2.0 only, has no
  870.             effect on 1.2/1.3).
  871.  
  872.         FREQF_STYLE - include gadgets so the user may select the font's
  873.             style.
  874.  
  875.     RTFO_Height - (ULONG) Suggested height of font requester window.
  876.  
  877.     RTFO_OkText - (char *) Replacement text for "Ok" gadget. Maximum 6
  878.         chars. (7 is still ok, but not esthetically pleasing)
  879.  
  880.     RTFO_SampleHeight - (ULONG) Height of font sample display in pixels
  881.         (default 24).
  882.  
  883.     RTFO_MinHeight - (ULONG) Minimum font size displayed.
  884.  
  885.     RTFO_MaxHeight - (ULONG) Maximum font size displayed.
  886.  
  887.     RTFO_FilterFunc - (struct Hook *) [V38] Call this hook for each
  888.         available font. Parameters are as follows:
  889.  
  890.         A0 - (struct Hook *) your hook
  891.         A2 - (struct rtFontRequester *) your filereq
  892.         A1 - (struct TextAttr *) textattr of font
  893.  
  894.         If your hook returns TRUE the font will be accepted. If it
  895.         returns FALSE the font will be skipped and will not appear in
  896.         the requester. IMPORTANT NOTE:  If you change your hook's
  897.         behavior you _MUST_ purge the requester's buffer (using
  898.         rtFreeReqBuffer())!
  899.  
  900.     RESULT
  901.     bool - TRUE if the user selected a font (freq->Attr holds the
  902.         font), FALSE if the requester was canceled.
  903.  
  904.     NOTE
  905.     You CANNOT call the font requester from a task because it may use
  906.     DOS calls!
  907.  
  908.     Automatically adjusts the requester to the screen font.
  909.  
  910.     If the requester got too big for the screen because of a very large
  911.     font, the topaz.font will be used.
  912.  
  913.     rtFontRequest() checks the pr_WindowPtr of your process to find the
  914.     screen to put the requester on.
  915.  
  916.     BUGS
  917.     none known
  918.  
  919.     SEE ALSO
  920.  
  921. reqtools.library/rtFreeFileList               reqtools.library/rtFreeFileList
  922.  
  923.     NAME
  924.     rtFreeFileList -- Free rtFileRequest() multiselection list.
  925.  
  926.     SYNOPSIS
  927.     rtFreeFileList( filelist );
  928.  
  929.     void rtFreeFileList( struct rtFileList * );
  930.                          A0
  931.  
  932.     DESCRIPTION
  933.     Frees a filelist returned by rtFileRequest() when the
  934.     FREQF_MULTISELECT flag was set. Call this after you have scanned
  935.     the filelist and you no longer need it.
  936.  
  937.     INPUTS
  938.     filelist - pointer to rtFileList structure, returned by
  939.         rtFileRequest() (may be NULL).
  940.  
  941.     RESULT
  942.     none
  943.  
  944.     BUGS
  945.     none known
  946.  
  947.     SEE ALSO
  948.     rtFileRequest()
  949.  
  950. reqtools.library/rtFreeReqBuffer             reqtools.library/rtFreeReqBuffer
  951.  
  952.     NAME
  953.     rtFreeReqBuffer -- Free buffered files in a file/font requester.
  954.  
  955.     SYNOPSIS
  956.     rtFreeReqBuffer( req );
  957.  
  958.     void rtFreeReqBuffer( APTR );
  959.                               A1
  960.  
  961.     DESCRIPTION
  962.     Frees the buffer associated with 'req'. In case of a file requester
  963.     this function will deallocate the directory buffer, in case of a
  964.     font requester the font list.
  965.  
  966.     It is safe to call this function for requesters that have no
  967.     buffer, so you may call this for all requesters to free as much
  968.     memory as possible.
  969.  
  970.     INPUTS
  971.     req - pointer to requester.
  972.  
  973.     RESULT
  974.     none
  975.  
  976.     BUGS
  977.     none known
  978.  
  979.     SEE ALSO
  980.     rtFileRequest(), rtFontRequest()
  981.  
  982. reqtools.library/rtFreeRequest                 reqtools.library/rtFreeRequest
  983.  
  984.     NAME
  985.     rtFreeRequest -- Free a ReqTools requester structure.
  986.  
  987.     SYNOPSIS
  988.     rtFreeRequest( req );
  989.  
  990.     void rtFreeRequest( APTR );
  991.                             A1
  992.  
  993.     DESCRIPTION
  994.     Free requester structure previously allocated by rtAllocRequestA().
  995.     This will also free all buffers associated with the requester, so
  996.     there is no need to call rtFreeReqBuffer() first.
  997.  
  998.     INPUTS
  999.     req - pointer to requester (may be NULL).
  1000.  
  1001.     RESULT
  1002.     none
  1003.  
  1004.     BUGS
  1005.     none known
  1006.  
  1007.     SEE ALSO
  1008.     rtAllocRequestA()
  1009.  
  1010. reqtools.library/rtGetLongA                       reqtools.library/rtGetLongA
  1011.  
  1012.     NAME
  1013.     rtGetLongA -- Open a number requester.
  1014.  
  1015.     SYNOPSIS
  1016.     ret = rtGetLongA( &longvar, title, reqinfo, taglist );
  1017.  
  1018.     ULONG rtGetLongA
  1019.         ( ULONG *, char *, struct rtReqInfo *, struct TagItem * );
  1020.     D0    A1       A2      A3                  A0
  1021.  
  1022.     ret = rtGetLong( &longvar, title, reqinfo, tag1, ... );
  1023.  
  1024.     ULONG rtGetLong( ULONG *, char *, struct rtReqInfo *, Tag, ... );
  1025.  
  1026.     DESCRIPTION
  1027.     Puts up a requester to get a signed long (32-bit) number from the
  1028.     user.
  1029.  
  1030.     'reqinfo' can be used to customize the requester. For greater
  1031.     control use the tags listed below. The advantage of the rtReqInfo
  1032.     structure is that it is global, where tags have to be specified
  1033.     each function call. See libraries/reqtools.[hi] for a description
  1034.     of the rtReqInfo structure.
  1035.  
  1036.     INPUTS
  1037.     &longvar - address of long (32 bit!) variable to hold result.
  1038.     title - pointer to null terminated title of requester window.
  1039.     reqinfo - pointer to a rtReqInfo structure allocated with
  1040.         rtAllocRequest() or NULL.
  1041.     taglist  - pointer to a TagItem array.
  1042.  
  1043.     TAGS
  1044.     RT_Window - see rtEZRequestA()
  1045.  
  1046.     RT_IDCMPFlags - see rtEZRequestA()
  1047.  
  1048.     RT_ReqPos - see rtEZRequestA()
  1049.  
  1050.     RT_LeftOffset - see rtEZRequestA()
  1051.  
  1052.     RT_TopOffset - see rtEZRequestA()
  1053.  
  1054.     RT_PubScrName - see rtEZRequestA()
  1055.  
  1056.     RT_Screen - see rtEZRequestA()
  1057.  
  1058.     RT_ReqHandler - see rtEZRequestA()
  1059.  
  1060.     RT_WaitPointer - see rtEZRequestA()
  1061.  
  1062.     RT_Underscore - [V38] see rtEZRequestA() Only when you also use the
  1063.         RTGL_GadFmt tag.
  1064.  
  1065.     RT_LockWindow - [V38] see rtEZRequestA()
  1066.  
  1067.     RT_ScreenToFront - [V38] see rtEZRequestA()
  1068.  
  1069.     RT_ShareIDCMP - [V38] see rtEZRequestA()
  1070.  
  1071.     RT_Locale - [V38] see rtEZRequestA()
  1072.  
  1073.     RT_IntuiMsgFunc - [V38] see rtEZRequestA()
  1074.  
  1075.     RT_TextAttr - [V38] see rtEZRequestA(). Note that under 1.2/1.3 the
  1076.         string gadget's font will remain the screen font.
  1077.  
  1078.     RTGL_Min - (ULONG) Minimum allowed value. If the user tries to
  1079.         enter a smaller value the requester will refuse to accept it.
  1080.  
  1081.     RTGL_Max - (ULONG) Maximum allowed value, higher values are refused.
  1082.  
  1083.     RTGL_Width - (ULONG) Width of requester window in pixels. This is
  1084.         only a suggestion. rtGetLongA() will not go below a certain
  1085.         width.
  1086.  
  1087.     RTGL_ShowDefault - (BOOL) If this is TRUE (default) the value
  1088.         already in 'longvar' will be displayed in the requester when it
  1089.         comes up. If set to FALSE the requester will be empty.
  1090.  
  1091.     RTGL_GadFmt - (char *) [V38] Using this tag you can offer the user
  1092.         several responses. See rtEZRequestA() for more information.
  1093.         Note that selecting this gadget is considered a positive
  1094.         response so the integer in the gadget is copied to '&longvar'.
  1095.  
  1096.     RTGL_GadFmtArgs - (APTR) [V38] If you used formatting codes with
  1097.         RTGL_GadFmt use this tag to pass the arguments.
  1098.  
  1099.     RTGL_Invisible - (BOOL) [V38] Using this tag you can switch on
  1100.         invisible typing. Very useful if you need to get something like
  1101.         a code number from the user. It is strongly advised to use
  1102.         { RTGL_ShowDefault, FALSE } or the user may get very confused! 
  1103.         Default is FALSE.
  1104.  
  1105.     RTGL_BackFill - (BOOL) [V38] Backfill requester window with
  1106.         pattern. Default TRUE.
  1107.  
  1108.     RTGL_TextFmt - (char *) [V38] Print these lines of text above the
  1109.         gadget in the requester. Very useful to inform the user of what
  1110.         he should enter. Most of the time you will also want to set the
  1111.         GLREQF_CENTERTEXT flag. If you set the RTGL_BackFill tag to
  1112.         FALSE _no_ recessed border will be placed around the text.
  1113.         Formatting codes may be used in the string (see
  1114.         RTGL_TextFmtArgs tag).
  1115.  
  1116.     RTGL_TextFmtArgs - (APTR) [V38] If you used formatting codes with
  1117.         RTGL_TextFmt use this tag to pass the arguments.
  1118.  
  1119.     RTGL_Flags - (ULONG) [V38]
  1120.  
  1121.         GLREQF_CENTERTEXT - centers each line of text above the gadget
  1122.             in the requester window. Should be generally set.
  1123.  
  1124.         GLREQF_HIGHLIGHTTEXT - Highlight text above the gadget. You
  1125.             will normally only want to use this if you also turned off
  1126.             the window backfilling.
  1127.  
  1128.     RESULT
  1129.     ret - TRUE if user entered a number, FALSE if not. If one of your
  1130.         idcmp flags caused the requester to end 'ret' will hold this
  1131.         flag. If you used the RTGL_GadFmt tag the return code will hold
  1132.         the value of the response as with rtEZRequestA().
  1133.  
  1134.     NOTE
  1135.     'longvar' will NOT change if the requester is aborted.
  1136.  
  1137.     Automatically adjusts the requester to the screen font.
  1138.  
  1139.     rtGetLongA() checks the pr_WindowPtr of your process to find the
  1140.     screen to put the requester on.
  1141.  
  1142.     If you use the RTGL_GadFmt tag the return value is not always the
  1143.     gadget the user selected. If the integer gadget is empty and the
  1144.     user presses the leftmost gadget (normally 'Ok') rtGetLong() will
  1145.     return 0 (FALSE)! If the integer gadget is empty and the user
  1146.     presses one of the other gadgets rtGetLong() _will_ return its
  1147.     value!
  1148.     Important: &longvar will not be changed in either of these cases.
  1149.  
  1150.     BUGS
  1151.     none known
  1152.  
  1153.     SEE ALSO
  1154.  
  1155. reqtools.library/rtGetStringA                   reqtools.library/rtGetStringA
  1156.  
  1157.     NAME
  1158.     rtGetStringA -- Open a string requester.
  1159.  
  1160.     SYNOPSIS
  1161.     ret = rtGetStringA( buffer, maxchars, title, reqinfo, taglist );
  1162.  
  1163.     ULONG rtGetStringA
  1164.         ( UBYTE *, ULONG, char *, struct rtReqInfo *, struct TagItem * );
  1165.     D0    A1       D0     A2      A3                  A0
  1166.  
  1167.     ret = rtGetString( buffer, maxchars, title, reqinfo, tag1, ... );
  1168.  
  1169.     ULONG rtGetString
  1170.         ( UBYTE *, ULONG, char *, struct rtReqInfo *, Tag, ... );
  1171.  
  1172.     DESCRIPTION
  1173.     Puts up a string requester to get a line of text from the user. The
  1174.     string present in 'buffer' upon entry will be displayed, ready to
  1175.     be edited.
  1176.  
  1177.     'reqinfo' can be used to customize the requester. For greater
  1178.     control use the tags listed below. The advantage of the rtReqInfo
  1179.     structure is that it is global, where tags have to be specified
  1180.     each function call. See libraries/reqtools.[hi] for a description
  1181.     of the rtReqInfo structure.
  1182.  
  1183.     INPUTS
  1184.     buffer - pointer to buffer to hold characters entered.
  1185.     maxchars - maximum number of characters that fit in buffer
  1186.         (EX-cluding the 0 to terminate the string !).
  1187.     title - pointer to null terminated title of requester window.
  1188.     reqinfo - pointer to a rtReqInfo structure allocated with
  1189.         rtAllocRequest() or NULL.
  1190.     taglist - pointer to a TagItem array.
  1191.  
  1192.     TAGS
  1193.     RT_Window - see rtEZRequestA()
  1194.  
  1195.     RT_IDCMPFlags - see rtEZRequestA()
  1196.  
  1197.     RT_ReqPos - see rtEZRequestA()
  1198.  
  1199.     RT_LeftOffset - see rtEZRequestA()
  1200.  
  1201.     RT_TopOffset - see rtEZRequestA()
  1202.  
  1203.     RT_PubScrName - see rtEZRequestA()
  1204.  
  1205.     RT_Screen - see rtEZRequestA()
  1206.  
  1207.     RT_ReqHandler - see rtEZRequestA()
  1208.  
  1209.     RT_WaitPointer - see rtEZRequestA()
  1210.  
  1211.     RT_Underscore - [V38] see rtEZRequestA(). Only when you also use
  1212.         the RTGS_GadFmt tag.
  1213.  
  1214.     RT_LockWindow - [V38] see rtEZRequestA()
  1215.  
  1216.     RT_ScreenToFront - [V38] see rtEZRequestA()
  1217.  
  1218.     RT_ShareIDCMP - [V38] see rtEZRequestA()
  1219.  
  1220.     RT_Locale - [V38] see rtEZRequestA()
  1221.  
  1222.     RT_IntuiMsgFunc - [V38] see rtEZRequestA()
  1223.  
  1224.     RT_TextAttr - [V38] see rtEZRequestA(). Note that under 1.2/1.3 the
  1225.         string gadget's font will remain the screen font.
  1226.  
  1227.     RTGS_Width - (ULONG) Width of requester window in pixels. This is
  1228.         only a suggestion. rtGetStringA() will not go below a certain
  1229.         width.
  1230.  
  1231.     RTGS_AllowEmpty - (BOOL) If RTGS_AllowEmpty is TRUE an empty string
  1232.         will also be accepted and returned. Defaults to FALSE, meaning
  1233.         that if the user enters an empty string the requester will be
  1234.         canceled.
  1235.  
  1236.     RTGS_GadFmt - (char *) [V38] Using this tag you can offer the user
  1237.         severalresponses. See rtEZRequestA() for more information. Note
  1238.         that selecting this gadget is considered a positive response so
  1239.         the string in the gadget is copied to 'buffer'.
  1240.  
  1241.     RTGS_GadFmtArgs - (APTR) [V38] If you used formatting codes with
  1242.         RTGS_GadFmt use this tag to pass the arguments.
  1243.  
  1244.     RTGS_Invisible - (BOOL) [V38] Using this tag you can switch on
  1245.         invisible typing. Very useful if you need to get something like
  1246.         a password from the user. It is strongly advised to use an
  1247.         empty initial string or the user may get very confused! 
  1248.         Default is FALSE.
  1249.  
  1250.     RTGS_BackFill - (BOOL) [V38] Backfill requester window with
  1251.         pattern. Default TRUE.
  1252.  
  1253.     RTGS_TextFmt - (char *) [V38] Print these lines of text above the
  1254.         gadget in the requester. Very useful to inform the user of what
  1255.         he should enter. Most of the time you will also want to set the
  1256.         GSREQF_CENTERTEXT flag. If you set the RTGS_BackFill tag to
  1257.         FALSE _no_ recessed border will be placed around the text.
  1258.         Formatting codes may be used in the string (see
  1259.         RTGS_TextFmtArgs tag).
  1260.  
  1261.     RTGS_TextFmtArgs - (APTR) [V38] If you used formatting codes with
  1262.         RTGS_TextFmt use this tag to pass the arguments.
  1263.  
  1264.     RTGS_Flags - (ULONG) [V38]
  1265.  
  1266.         GSREQF_CENTERTEXT - centers each line of text above the gadget
  1267.             in the requester window. Should be generally set.
  1268.  
  1269.         GSREQF_HIGHLIGHTTEXT - Highlight text above the gadget. You
  1270.             will normally only want to use this if you also turned off
  1271.             the window backfilling.
  1272.  
  1273.     RESULT
  1274.     ret - TRUE if user entered something, FALSE if not. If one of your
  1275.         idcmp flags caused the requester to end 'ret' will hold this
  1276.         flag. If you used the RTGS_GadFmt tag the return code will hold
  1277.         the value of the response as with rtEZRequestA().
  1278.  
  1279.     NOTE
  1280.     The contents of the buffer will NOT change if the requester is
  1281.     aborted.
  1282.  
  1283.     Automatically adjusts the requester to the screen font.
  1284.  
  1285.     rtGetStringA() checks the pr_WindowPtr of your process to find the
  1286.     screen to put the requester on.
  1287.  
  1288.     If you use the RTGS_GadFmt tag the return value is not always the
  1289.     gadget the user selected. If the string gadget is empty and the
  1290.     user presses the leftmost gadget (normally 'Ok') rtGetString() will
  1291.     return 0 (FALSE)! If the string gadget is empty and the user
  1292.     presses one of the other gadgets rtGetString() _will_ return its
  1293.     value!  Important: 'buffer' will not be changed in either of these
  1294.     cases.
  1295.     If you set the RTGS_AllowEmpty tag to TRUE 'buffer' will always be
  1296.     changed of course, and rtGetString() will always return the value
  1297.     of the gadget pressed.
  1298.  
  1299.     BUGS
  1300.     none known
  1301.  
  1302.     SEE ALSO
  1303.  
  1304. reqtools.library/rtGetVScreenSize           reqtools.library/rtGetVScreenSize
  1305.  
  1306.     NAME
  1307.     rtGetVScreenSize -- Get visible size of a screen.
  1308.  
  1309.     SYNOPSIS
  1310.     spacing = rtGetVScreenSize( screen, widthptr, heightptr );
  1311.  
  1312.     ULONG rtGetVScreenSize( struct Screen *, ULONG *, ULONG * );
  1313.     D0                      A0               A1       A2
  1314.  
  1315.     DESCRIPTION
  1316.     Use this function to get the size of the visible portion of a
  1317.     screen.
  1318.  
  1319.     The value returned by rtGetVScreenSize() can be used for vertical
  1320.     spacing. It will be larger for interlaced and productivity screens.
  1321.     Using this number for spacing will assure your requester will look
  1322.     good on an interlaced and a non-interlaced screen.
  1323.  
  1324.     Current return codes are 2 for non-interlaced and 4 for interlaced.
  1325.     These values may change in the future, don't depend on them too
  1326.     much. They will in any case remain of the same magnitude.
  1327.  
  1328.     INPUTS
  1329.     screen - pointer to the screen.
  1330.     widthptr - address of an ULONG variable to hold the width.
  1331.     heightptr - address of an ULONG variable to hold the height.
  1332.  
  1333.     RESULT
  1334.     spacing - vertical spacing for the screen.
  1335.  
  1336.     NOTE
  1337.     This function is for the advanced ReqTools user.
  1338.  
  1339.     BUGS
  1340.  
  1341.     SEE ALSO
  1342.  
  1343. reqtools.library/rtLockWindow                   reqtools.library/rtLockWindow
  1344.  
  1345.     NAME
  1346.     rtLockWindow [V38] -- Block a window from user input and show busy
  1347.         pointer.
  1348.  
  1349.     SYNOPSIS
  1350.     windowlock = rtLockWindow( window );
  1351.  
  1352.     APTR rtLockWindow( struct Window * );
  1353.     D0                 A0
  1354.  
  1355.     DESCRIPTION
  1356.     Lock a window so it will no longer accept any user input. The only
  1357.     functions left to the user are depth arrangement and window
  1358.     dragging. All gadgets will be un-selectable and the window can not
  1359.     be resized.
  1360.     
  1361.     It will also get the standard wait pointer set. The pointer at the
  1362.     time of locking will be restored when the window is unlocked (this
  1363.     will *not* happen on Kickstart V39 or higher!).
  1364.  
  1365.     You may nest calls to rtLockWindow() and rtUnlockWindow(). Make sure
  1366.     you unlock the window in the correct (opposite) order.
  1367.  
  1368.     See the RT_LockWindow tag for an automatic way of locking your
  1369.     window.
  1370.  
  1371.     Use this function (and rtUnlockWindow()) instead of
  1372.     rtSetWaitPointer().
  1373.  
  1374.     INPUTS
  1375.     window - pointer to the window to be locked.
  1376.  
  1377.     RESULT
  1378.     windowlock - a pointer to a (private) window lock. You must pass
  1379.         this to rtUnlockWindow() to unlock the window again. Never mind
  1380.         if this is NULL. This means there was not enough memory and the
  1381.         window will not be locked. There is no sense in reporting this,
  1382.         just carry on and pass the NULL window lock to rtUnlockWindow().
  1383.  
  1384.     NOTE
  1385.     The wait pointer will look exactly like the standard Workbench 2.0
  1386.     wait pointer. In combination with PointerX, ClockTick or
  1387.     LacePointer the handle will turn.
  1388.  
  1389.     BUGS
  1390.     none known
  1391.  
  1392.     SEE ALSO
  1393.  
  1394. reqtools.library/rtPaletteRequestA         reqtools.library/rtPaletteRequestA
  1395.  
  1396.     NAME
  1397.     rtPaletteRequestA -- Open a palette requester.
  1398.  
  1399.     SYNOPSIS
  1400.     color = rtPaletteRequestA( title, reqinfo, taglist );
  1401.  
  1402.     LONG rtPaletteRequestA
  1403.         ( char *, struct rtReqInfo *, struct TagItem * );
  1404.     D0    A2      A3                  A0
  1405.  
  1406.     color = rtPaletteRequest( title, reqinfo, tag1, ... );
  1407.  
  1408.     LONG rtPaletteRequest( char *, struct rtReqInfo *, Tag, ... );
  1409.  
  1410.     DESCRIPTION
  1411.     Put up a palette requester so the user can change the screen's
  1412.     colors.
  1413.  
  1414.     The colors are changed in the viewport of the screen the requester
  1415.     will appear on, so that is where you will find them after the
  1416.     palette requester returns.
  1417.  
  1418.     The selected color is returned, so you can also use this requester
  1419.     to let the user select a color.
  1420.  
  1421.     'reqinfo' can be used to customize the requester. For greater
  1422.     control use the tags listed below. The advantage of the rtReqInfo
  1423.     structure is that it is global, where tags have to be specified
  1424.     each function call. See libraries/reqtools.[hi] for a description
  1425.     of the rtReqInfo structure.
  1426.  
  1427.     INPUTS
  1428.     title - pointer to requester window title (null terminated).
  1429.     reqinfo - pointer to a rtReqInfo structure allocated with
  1430.         rtAllocRequest() or NULL.
  1431.     taglist - pointer to a TagItem array.
  1432.  
  1433.     TAGS
  1434.     RT_Window - see rtEZRequestA()
  1435.  
  1436.     RT_ReqPos - see rtEZRequestA()
  1437.  
  1438.     RT_LeftOffset - see rtEZRequestA()
  1439.  
  1440.     RT_TopOffset - see rtEZRequestA()
  1441.  
  1442.     RT_PubScrName - see rtEZRequestA()
  1443.  
  1444.     RT_Screen - see rtEZRequestA()
  1445.  
  1446.     RT_ReqHandler - see rtEZRequestA()
  1447.  
  1448.     RT_WaitPointer - see rtEZRequestA()
  1449.  
  1450.     RT_LockWindow - [V38] see rtEZRequestA()
  1451.  
  1452.     RT_ScreenToFront - [V38] see rtEZRequestA()
  1453.  
  1454.     RT_ShareIDCMP - [V38] see rtEZRequestA()
  1455.  
  1456.     RT_Locale - [V38] see rtEZRequestA()
  1457.  
  1458.     RT_IntuiMsgFunc - [V38] see rtEZRequestA()
  1459.  
  1460.     RT_DefaultFont - (struct TextFont *) This tag allows you to specify
  1461.         the font to be used in the requester when the screen font is
  1462.         proportional. Default is GfxBase->DefaultFont. This tag is
  1463.         obsolete in ReqTools 2.2 and higher, when running OS 3.0 or
  1464.         higher!
  1465.  
  1466.     RT_TextAttr - [V38] see rtFileRequestA() If the font is
  1467.         proportional on Kickstart 2.04 or below ReqTools will use the
  1468.         system default font or the font supplied with RT_DefaultFont.
  1469.         On Kickstart 3.0 or higher the proportional font is used.
  1470.  
  1471.     RTPA_Color - (ULONG) Initially selected color of palette. Default
  1472.         is 1.
  1473.  
  1474.     RESULT
  1475.     color - the color number of the selected color or -1 if the user
  1476.         canceled the requester.
  1477.  
  1478.     NOTE
  1479.     Automatically adjusts the requester to the screen font. On
  1480.     Kickstart 2.04 or lower, if the screen font is proportional the
  1481.     default font will be used.
  1482.  
  1483.     If the requester got too big for the screen because of a very large
  1484.     font, the topaz.font will be used.
  1485.  
  1486.     rtPaletteRequestA() checks the pr_WindowPtr of your process to find
  1487.     the screen to put the requester on.
  1488.  
  1489.     BUGS
  1490.     none known
  1491.  
  1492.     SEE ALSO
  1493.  
  1494. reqtools.library/rtReqHandlerA                 reqtools.library/rtReqHandlerA
  1495.  
  1496.     NAME
  1497.     rtReqHandlerA -- Handle asyncronous ReqTools requesters.
  1498.  
  1499.     SYNOPSIS
  1500.     ret = rtReqHandlerA( handlerinfo, sigs, taglist );
  1501.  
  1502.     ULONG rtReqHandlerA
  1503.         ( struct rtHandlerInfo *, ULONG, struct TagItem * );
  1504.     D0    A1                      D0     A0
  1505.  
  1506.     ret = rtReqHandler( handlerinfo, sigs, tag1, ... );
  1507.  
  1508.     ULONG rtReqHandler( struct rtHandlerInfo *, ULONG, Tag, ... );
  1509.  
  1510.     DESCRIPTION
  1511.     This function should be called if you used the RT_ReqHandler tag
  1512.     with a requester function.
  1513.  
  1514.     The requester you used the tag with will have returned immediately
  1515.     after its initialization and will have initialized a pointer to a
  1516.     rtHandlerInfo structure for you. You should now do the following:
  1517.  
  1518.     Check the DoNotWait field. If it is FALSE you have to wait for the
  1519.     signals in the WaitMask field (plus your own signals if you like).
  1520.     If any of the signals in WaitMask are received or DoNotWait was not
  1521.     FALSE you have to call rtReqHandlerA() and check its return value
  1522.     for one of the following values:
  1523.  
  1524.     CALL_HANDLER - Check DoNotWait again, Wait() if you have to and
  1525.         call rtReqHandlerA() again. In other words, loop.
  1526.     everything else - normal return value, requester has finished. This
  1527.         return value will be the same as if the requester had run
  1528.         normally.
  1529.  
  1530.     You must pass the signals you received to rtReqHandlerA().
  1531.  
  1532.     NOTE: if you want to wait for your own signals do not do so if
  1533.         DoNotWait is TRUE. Call rtReqHandlerA() and if you must know if
  1534.         one of your signals arrived use SetSignal() to find this out.
  1535.         If you are waiting for a message to arrive at a message port
  1536.         you can simple call GetMsg() and check if it is non-null.
  1537.         DoNotWait will naturally only be TRUE when it absolutely,
  1538.         positively has to be. A multitasking machine as the Amiga
  1539.         should use Wait() as much as possible.
  1540.  
  1541.     This is an example of a "requester loop":
  1542.  
  1543.     ...
  1544.     struct rtHandlerInfo *hinfo;
  1545.     ULONG ret, mymask, sigs;
  1546.  
  1547.     ...
  1548.     /* calculate our mask */
  1549.     mymask = 1 << win->UserPort->mp_SigBit;
  1550.  
  1551.     /* We use the RT_ReqHandler tag to cause the requester to return
  1552.        after initializing.
  1553.        Check the return value to see if this setup went ok. */
  1554.     if( rtFontRequest( req, "Font", RT_ReqHandler, &hinfo, TAG_END )
  1555.                                                    == CALL_HANDLER )
  1556.     {
  1557.         do
  1558.         {
  1559.             /* Wait() if we can */
  1560.             if( !hinfo->DoNotWait )
  1561.             {
  1562.                 sigs = Wait( hinfo->WaitMask | mymask );
  1563.             }
  1564.             
  1565.             /* check our own message port */
  1566.             while( msg = GetMsg( win->UserPort ) )
  1567.             {
  1568.                 ...
  1569.                 /* here we handle messages received at our windows
  1570.                    IDCMP port */
  1571.                 ...
  1572.             }
  1573.  
  1574.             /* let the requester do its thing (remember to pass 'sigs') */
  1575.             ret = rtReqHandler( hinfo, sigs, TAG_END );
  1576.  
  1577.             /* continue this loop as long as the requester is up */
  1578.         } while( ret == CALL_HANDLER )
  1579.  
  1580.         /* when we get here we know the requester has finished, 'ret'
  1581.            is the return code. */
  1582.         ...
  1583.         }
  1584.     else
  1585.     {
  1586.         notify( "Error opening requester!" );
  1587.     }
  1588.     ...
  1589.  
  1590.     INPUTS
  1591.     handlerinfo - pointer to handler info structure initialized by
  1592.         using the RT_ReqHandler tag when calling a requester function.
  1593.     sigs - the signals received by previous wait, will be ignored if
  1594.         handlerinfo->DoNotWait was TRUE.
  1595.     taglist - pointer to a TagItem array.
  1596.  
  1597.     TAGS
  1598.     RTRH_EndRequest - supplying this tag will end the requester. The
  1599.         return code from rtReqHandlerA() will _not_ be CALL_HANDLER,
  1600.         but the requester return code. If the tagdata of this tag is
  1601.         REQ_CANCEL the requester will be canceled, if it is REQ_OK the
  1602.         requester will be ok-ed. In case of an EZRequest tagdata should
  1603.         be the return code of the requester (TRUE, FALSE or 2,3,4,...).
  1604.  
  1605.     RESULT
  1606.     ret - CALL_HANDLER if you have to call rtReqHandlerA() again, or
  1607.         the normal return value from the requester.
  1608.  
  1609.     BUGS
  1610.     none known
  1611.  
  1612.     SEE ALSO
  1613.     rtEZRequest() (RT_ReqHandler explanation)
  1614.  
  1615. reqtools.library/rtScreenModeRequestA   reqtools.library/rtScreenModeRequestA
  1616.  
  1617.     NAME
  1618.     rtScreenModeRequestA [V38] -- Open a screen mode requester.
  1619.  
  1620.     SYNOPSIS
  1621.     ret = rtScreenModeRequestA( screenmodereq, title, taglist );
  1622.  
  1623.     BOOL rtScreenModeRequestA
  1624.         ( struct rtScreenModeRequester *, char *, struct TagItem * );
  1625.     D0    A1                              A3      A0
  1626.  
  1627.     ret = rtScreenModeRequest( screenmodereq, title, tag1, ... );
  1628.  
  1629.     BOOL rtScreenModeRequest
  1630.         ( struct rtScreenModeRequester *, char *, Tag, ... );
  1631.  
  1632.     DESCRIPTION
  1633.     *IMPORTANT* THIS REQUESTER IS ONLY AVAILABLE FROM KICKSTART 2.0
  1634.         ONWARDS! The 1.3 version of ReqTools also contains the
  1635.         screenmode requester, but unless you are running 2.0 or higher
  1636.         it will not come up. So what you essentially have to do is NOT
  1637.         call rtScreenModeRequestA() if your program is running on a
  1638.         machine with Kickstart 1.2/1.3. You can safely call
  1639.         rtScreenModeRequestA() if you are running on a 2.0 machine,
  1640.         even if the user has installed the 1.3 version of ReqTools.
  1641.  
  1642.     Get a screen mode from the user.
  1643.  
  1644.     The user will be able to pick a screen mode by name, enter the size
  1645.     and the number of colors (bitplane depth).
  1646.  
  1647.     rtScreenModeRequestA() will call the appropriate 2.0 functions to
  1648.     get all the mode's information. If no name has been assigned to the
  1649.     mode one will be constructed automatically.
  1650.  
  1651.     INPUTS
  1652.     screenmodereq - pointer to a struct rtScreenModeRequester allocated
  1653.         with rtAllocRequestA().
  1654.     title - pointer to requester window title (null terminated).
  1655.     taglist - pointer to a TagItem array.
  1656.  
  1657.     TAGS
  1658.     RT_Window - see rtEZRequestA()
  1659.  
  1660.     RT_ReqPos - see rtEZRequestA()
  1661.  
  1662.     RT_LeftOffset - see rtEZRequestA()
  1663.  
  1664.     RT_TopOffset - see rtEZRequestA()
  1665.  
  1666.     RT_PubScrName - see rtEZRequestA()
  1667.  
  1668.     RT_Screen - see rtEZRequestA()
  1669.  
  1670.     RT_ReqHandler - see rtEZRequestA()
  1671.  
  1672.     RT_WaitPointer - see rtEZRequestA()
  1673.  
  1674.     RT_LockWindow - see rtEZRequestA()
  1675.  
  1676.     RT_ScreenToFront - see rtEZRequestA()
  1677.  
  1678.     RT_ShareIDCMP - see rtEZRequestA()
  1679.  
  1680.     RT_Locale - see rtEZRequestA()
  1681.  
  1682.     RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call
  1683.         this hook for each IDCMP message it gets that doesn't belong to
  1684.         its window. Only applies if you used the RT_ShareIDCMP tag to
  1685.         share the IDCMP port with the parent window. Parameters are as
  1686.         follows:
  1687.  
  1688.         A0 - (struct Hook *) your hook
  1689.         A2 - (struct rtScreenModeRequester *) your req
  1690.         A1 - (struct IntuiMessage *) the message
  1691.  
  1692.         After you have finished examining the message and your hook
  1693.         returns, ReqTools will reply the message. So do not reply the
  1694.         message yourself!
  1695.  
  1696.     RT_Underscore - (char) [V38] Indicates the symbol that precedes the
  1697.         character in a gadget's label to be underscored. This will also
  1698.         define the keyboard shortcut for this gadget. Currently only
  1699.         needed for RTSC_OkText. Usually set to '_'.
  1700.  
  1701.     RT_DefaultFont - (struct TextFont *) This tag allows you to specify
  1702.         the font to be used in the requester when the screen font is
  1703.         proportional. Default is GfxBase->DefaultFont. This tag is
  1704.         obsolete in ReqTools 2.2 and higher.
  1705.  
  1706.     RT_TextAttr - [V38] see rtFileRequestA()
  1707.  
  1708.     RTSC_Flags - (ULONG) Several flags:
  1709.  
  1710.         SCREQF_OVERSCANGAD - Add an overscan cycle gadget to the
  1711.             requester. After the requester returns you may read the
  1712.             overscan type in 'rq->OverscanType' If this is 0 no
  1713.             overscan is selected (Regular Size), if non-zero it holds
  1714.             one of the OSCAN_... values defined in the include file
  1715.             'intuition/screens.[h|i]'.
  1716.  
  1717.         SCREQF_AUTOSCROLLGAD - Add an autoscroll checkbox gadget to the
  1718.             requester. After the requester returns read
  1719.             'smreq->AutoScroll' to see if the user prefers autoscroll
  1720.             to be on or off.
  1721.  
  1722.         SCREQF_SIZEGADS - Add width and height gadgets to the
  1723.             requester. If you do not add these gadgets the width and
  1724.             height returned will be the default width and height for
  1725.             the selected overscan type.
  1726.  
  1727.         SCREQF_DEPTHGAD - Add a depth slider gadget to the requester.
  1728.             If you do not add a depth gadget, the depth returned will
  1729.             be the maximum depth this mode can be opened in.
  1730.  
  1731.         SCREQF_NONSTDMODES - Include all modes. Unless this flag is set
  1732.             rtScreenModeRequestA() will exclude nonstandard modes.
  1733.             Nonstandard modes are presently HAM and EHB
  1734.             (ExtraHalfBrite). So unless you are picking a mode to do
  1735.             some rendering in leave this flag unset. Without this flag
  1736.             set the mode returned will be a normal bitplaned mode.
  1737.  
  1738.         SCREQF_GUIMODES - Set this flag if you are getting a screen
  1739.             mode to open a user interface screen in. The modes shown
  1740.             will be standard modes with a high enough resolution
  1741.             (minumum 640 pixels). If this flag is set the
  1742.             SCREQF_NONSTDMODES flag is ignored.
  1743.  
  1744.     RTSC_Height - (ULONG) Suggested height of screenmode requester
  1745.         window.
  1746.  
  1747.     RTSC_OkText - (char *) Replacement text for "Ok" gadget, max 6
  1748.         chars long.
  1749.  
  1750.     RTSC_MinWidth - (UWORD) The minimum display width allowed.
  1751.  
  1752.     RTSC_MaxWidth - (UWORD) The maximum display width allowed.
  1753.  
  1754.     RTSC_MinHeight - (UWORD) The minimum display height allowed.
  1755.  
  1756.     RTSC_MaxHeight - (UWORD) The maximum display height allowed.
  1757.  
  1758.     RTSC_MinDepth - (UWORD) The minimum display depth allowed. Modes
  1759.         with a minimum display depth lower than this value will not be
  1760.         included in the list.
  1761.  
  1762.     RTSC_MaxDepth - (UWORD) The maximum display depth allowed.
  1763.  
  1764.     RTSC_PropertyFlags - (ULONG) A mode must have these property flags
  1765.         to be included. Only bits set in RTSC_PropertyMask are
  1766.         considered.
  1767.  
  1768.     RTSC_PropertyMask - (ULONG) Mask to apply to RTSC_PropertyFlags to
  1769.         determine which bits to consider. See use of 'newsignals' and
  1770.         'signalmask' in exec.library/SetSignal(). Default is to
  1771.         consider all bits in RTSC_PropertyFlags as significant.
  1772.  
  1773.     RTSC_FilterFunc - (struct Hook *) Call this hook for each display
  1774.         mode id in the system's list. Parameters are as follows:
  1775.  
  1776.         A0 - (struct Hook *) your hook
  1777.         A2 - (struct rtScreenModeRequester *) your req
  1778.         A1 - (ULONG) 32-bit extended mode id
  1779.  
  1780.         If your hook returns TRUE the mode will be accepted. If it
  1781.         returns FALSE the mode will be skipped and will not appear in
  1782.         the requester.
  1783.  
  1784.     RESULT
  1785.     ret - FALSE if the requester was canceled or TRUE if the user
  1786.         selected a screen mode (check 'smreq->DisplayID' for the 32-bit
  1787.         extended display mode, 'smreq->DisplayWidth' and
  1788.         'smreq->DisplayHeight' for the display size,
  1789.         'smreq->DisplayDepth' for the screen's depth).
  1790.  
  1791.     NOTE
  1792.     Automatically adjusts the requester to the screen font.
  1793.  
  1794.     If the requester got too big for the screen because of a very large
  1795.     font, the topaz.font will be used.
  1796.  
  1797.     rtScreenModeRequest() checks the pr_WindowPtr of your process to
  1798.     find the screen to put the requester on.
  1799.  
  1800.     BUGS
  1801.     none known
  1802.  
  1803.     SEE ALSO
  1804.     graphics/GetDisplayInfoData(), graphics/displayinfo.h,
  1805.     exec.library/SetSignal(), Intuition/SA_DisplayID screen tag
  1806.  
  1807. reqtools.library/rtScreenToFrontSafely reqtools.library/rtScreenToFrontSafely
  1808.  
  1809.     NAME
  1810.     rtScreenToFrontSafely -- Bring a screen to the front.
  1811.  
  1812.     SYNOPSIS
  1813.     rtScreenToFrontSafely( screen );
  1814.  
  1815.     void rtScreenToFrontSafely( struct Screen * );
  1816.                                 A0
  1817.  
  1818.     DESCRIPTION
  1819.     Brings the specified screen to the front of the display, but only
  1820.     after checking it is still in the list of currently open screens.
  1821.  
  1822.     This function can be used to bring a screen back to the front of
  1823.     the display after bringing another screen to the front. If the
  1824.     first screen closed while you where busy it is harmless to call
  1825.     this function, unlike calling the normal ScreenToFront().
  1826.  
  1827.     INPUTS
  1828.     screen - pointer to the screen.
  1829.  
  1830.     RESULT
  1831.     none
  1832.  
  1833.     NOTE
  1834.     This function is for the advanced ReqTools user.
  1835.  
  1836.     BUGS
  1837.     none known
  1838.  
  1839.     SEE ALSO
  1840.     intuition.library/ScreenToFront()
  1841.  
  1842. reqtools.library/rtSetReqPosition           reqtools.library/rtSetReqPosition
  1843.  
  1844.     NAME
  1845.     rtSetReqPosition -- Locate requester window according to position.
  1846.  
  1847.     SYNOPSIS
  1848.     rtSetReqPosition( reqpos, newwindow, screen, window );
  1849.  
  1850.     void rtSetReqPosition
  1851.         ( ULONG, struct NewWindow *, struct Screen *, struct Window * );
  1852.           D0     A0                  A1               A2
  1853.  
  1854.     DESCRIPTION
  1855.     Sets newwindow->LeftEdge and newwindow->TopEdge according to reqpos.
  1856.  
  1857.     Except for the left- and topedge 'newwindow' must already be
  1858.     completely initialized.
  1859.  
  1860.     The newwindow->LeftEdge and newwindow->TopEdge already in the
  1861.     NewWindow structure will be used as offsets to the requested
  1862.     position. If you'd like a window at position (25,18) from the top
  1863.     left of the screen you would fill newwindow->LeftEdge with 25,
  1864.     newwindow->TopEdge with 18 and call rtSetReqPosition() with reqpos
  1865.     equal to REQPOS_TOPLEFTSCR.
  1866.  
  1867.     Don't forget to make sure newwindow->LeftEdge and newwindow->TopEdge
  1868.     are 0 if you don't want to offset your window.
  1869.  
  1870.     In case of REQPOS_POINTER you can use them to point to your window's
  1871.     hotspot, where the pointer should point. If you call
  1872.     rtSetReqPosition() with the left- and topedge equal to 0 you'd get
  1873.     a window appearing with its top- and leftedge equal to the current
  1874.     pointer position.
  1875.  
  1876.     Note that the screen pointer may _NOT_ be NULL. If you have your
  1877.     own window open you can supply yourwindow->WScreen to this function.
  1878.  
  1879.     The window pointer is only required if reqpos is REQPOS_CENTERWIN or
  1880.     REQPOS_TOPLEFTWIN. Even in this case you may call rtSetReqPosition()
  1881.     with a NULL window pointer. The positions will simply fall back to
  1882.     REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR respectively.
  1883.  
  1884.     INPUTS
  1885.     reqpos - one of the REQPOS_... constants usable with RT_ReqPos.
  1886.     newwindow - pointer to your (already initialized) NewWindow
  1887.         structure.
  1888.     screen - pointer to screen the requester will appear on.
  1889.     window - pointer to parent window or NULL.
  1890.  
  1891.     RESULT
  1892.     none
  1893.  
  1894.     NOTE
  1895.     This function is for the advanced ReqTools user.
  1896.  
  1897.     BUGS
  1898.     none known
  1899.  
  1900.     SEE ALSO
  1901.     RT_ReqPos tag
  1902.  
  1903. reqtools.library/rtSetWaitPointer           reqtools.library/rtSetWaitPointer
  1904.  
  1905.     NAME
  1906.     rtSetWaitPointer -- Change pointer imate to that of a wait pointer.
  1907.  
  1908.     SYNOPSIS
  1909.     rtSetWaitPointer( window );
  1910.  
  1911.     void rtSetWaitPointer( struct Window * );
  1912.                            A0
  1913.  
  1914.     DESCRIPTION
  1915.     Change the window's pointer image to that of a wait pointer. Call
  1916.     this function whenever your program will be busy doing something
  1917.     for a lengthy period of time.
  1918.  
  1919.     It is recommended you call this function before calling any of the
  1920.     requester functions. This way if the user clicks in your window he
  1921.     will know he must respond to the requester before doing anything
  1922.     else. Also see the RT_WaitPointer tag for an automatic way of
  1923.     setting the wait pointer. If you are using ReqTools V38+ check out
  1924.     the RT_LockWindow tag!
  1925.  
  1926.     INPUTS
  1927.     window - pointer to the window to receive the wait pointer.
  1928.  
  1929.     RESULT
  1930.     none
  1931.  
  1932.     NOTE
  1933.     The wait pointer will look exactly like the standard Workbench 2.0
  1934.     wait pointer. In combination with PointerX, ClockTick or
  1935.     LacePointer the handle will turn.
  1936.  
  1937.     BUGS
  1938.     none known
  1939.  
  1940.     SEE ALSO
  1941.     rtEZRequest (RT_WaitPointer and RT_LockWindow tags), rtLockWindow()
  1942.  
  1943. reqtools.library/rtSpread                           reqtools.library/rtSpread
  1944.  
  1945.     NAME
  1946.     rtSpread -- Spread objects over a length.
  1947.  
  1948.     SYNOPSIS
  1949.     rtSpread( posarray, sizearray, totalsize, min, max, num );
  1950.  
  1951.     void rtSpread( ULONG *, ULONG *, ULONG, ULONG, ULONG, ULONG );
  1952.                    A0       A1       D0     D1     D2     D3
  1953.  
  1954.     DESCRIPTION
  1955.     Evenly spread a number of objects over a certain length. Primary
  1956.     use is for arrangement of gadgets in a window.
  1957.  
  1958.     Example:
  1959.  
  1960.     'sizearray' holds following values: 4, 6, 4, 2 and 8,
  1961.     'totalsize' is 24 (= 4 + 6 + 4 + 2 + 8),
  1962.     'min' is 3, 'max' is 43,
  1963.     and finally, 'num' is 5.
  1964.  
  1965.     After calling rtSpread() 'posarray' would hold the following
  1966.     values: 3, 11, 19, 26 and 31.
  1967.  
  1968.     My attempt at a visual representation:
  1969.  
  1970.       |                                            |
  1971.       |  |                                      |  |
  1972.       |  OOOO    OOOOOO    OOOO    OO    OOOOOOOO  |
  1973.       |  |                                      |  |
  1974.       |         1    1    2    2    3    3    4    4
  1975.       0----5----0----5----0----5----0----5----0----5
  1976.  
  1977.     INPUTS
  1978.     posarray - pointer to array to be filled with positions.
  1979.     sizearray - pointer to array of sizes.
  1980.     totalsize - total size of all objects (sum of all values in
  1981.         sizearray).
  1982.     min - first position to use.
  1983.     max - last position, first _NOT_ to use.
  1984.     num - number of objects (size of posarray and sizearray).
  1985.  
  1986.     RESULT
  1987.     none
  1988.  
  1989.     NOTE
  1990.     This function is for the advanced ReqTools user.
  1991.  
  1992.     BUGS
  1993.     none known
  1994.  
  1995.     SEE ALSO
  1996.  
  1997. reqtools.library/rtUnlockWindow               reqtools.library/rtUnlockWindow
  1998.  
  1999.     NAME
  2000.     rtUnlockWindow [V38] -- Ulock window locked with rtLockWindow().
  2001.  
  2002.     SYNOPSIS
  2003.     rtUnlockWindow( window, windowlock );
  2004.  
  2005.     void rtUnlockWindow( struct Window *, APTR );
  2006.                          A0               A1
  2007.  
  2008.     DESCRIPTION
  2009.     Unlock a window previously locked with rtLockWindow(). The window
  2010.     will once again accept user input and will get its original mouse
  2011.     pointer back (default or custom).
  2012.  
  2013.     Under Kickstart V39 or higher the original window pointer will not
  2014.     be restored if it was set using SetWindowPointer(). You will have to
  2015.     restore the pointer yourself in this case.
  2016.  
  2017.     INPUTS
  2018.     window - pointer to the window to be unlocked.
  2019.     windowlock - the windowlock pointer returned by rtLockWindow(), may
  2020.         be NULL.
  2021.  
  2022.     RESULT
  2023.     none
  2024.  
  2025.     BUGS
  2026.     none known
  2027.  
  2028.     SEE ALSO
  2029.     rtLockWindow()
  2030.  
  2031.